package com.videri.match.client;

import com.google.gwt.user.client.rpc.AsyncCallback;

public interface VideriMatchServiceAsync {
	
	/**
	 * This will add a new matching to the server
	 * @param match the matching to be added
	 * @param category the category to place the matching in
	 */
	public void addNewMatching(Matching match, String category, AsyncCallback callback);
	
	/**
	 * This will return a random matching game from the server
	 * @return a random matching game
	 */
	public void getMatching(AsyncCallback callback);
	
	/**
	 * This will locate a matching game on the server.  If category
	 * is set to true then the server will pick a random matching from
	 * the given category.  Otherwise the server will return the matching
	 * with the given name.
	 * @param name the name of the matching or category
	 * @param fromCategory whether name is a category or not
	 * @return a matching game
	 */
	public void getMatching(String name, boolean fromCategory, AsyncCallback callback);
	
	/**
	 * This will return a category containing the top numMatchings
	 * based on number of times played.
	 * @param name the name of the category
	 * @param numMatchings the number of matchings to include
	 * @return a new category with the same name, but only the top numMatchings
	 */
	public void getCategory(String name, int numMatchings, AsyncCallback callback);
	
	/**
	 * This will return all categories containing the top numMatchings
	 * for each category.
	 * @param numMatchings the number of matchings to include in each category
	 * @return a category array of all categories
	 */
	public void getAllCategories(int numMatchings, AsyncCallback callback);
	
	/**
	 * This will allow for the creation of a new user with the associated user info.
	 * @param userInfo The string array with the user's info specified
	 * @return If the new user was successfully created
	 */
	/* JUSTIN!!!  Here is where you can specify what properties we want the user to have.
	 * For right now let's assing the following:
	 * userInfo[0]=Last Name
	 * userInfo[1]=First Name
	 * userInfo[2]=Handle
	 * userInfo[3]=Password (We can encrypt it later if we want as a feature)
	 * userInfo[4]=e-mail
	 * 
	 * If you change this or add to it let me know!  Mike
	 */
	public void createNewUser(String[] userInfo, AsyncCallback callback);
	
	/**
	 * This will handle requests to login a user to system
	 * @param handle The user's handle
	 * @param password The user's password
	 * @return the string to be associated with the user during this session, an empty string indicates a failed login
	 */
	public void loginUser(String handle, String password, AsyncCallback callback);
	
	/**
	 * This will logout users from the system.  If the user is not logged in
	 * it will still appear as if the user has been successfully logged out.
	 * @param cookie The cookie for this log in session of the user to be logged out
	 * @return true if the user was successfully logged out
	 */
	public void logoutUser(String cookie, AsyncCallback callback);
	
	/**
	 * This will return the properties associated with the user (i.e. ranking, number of matches).
	 * This will only return a non-null pointer if the user is logged in!
	 * @param handle The user's handle to find the info
	 * @return a string array containing the user's properties
	 */
	/* For right now we'll use the following convention.  If you want this changed let me know! Mike
	 * [0] = integer ranking
	 * [1] = percentile ranking
	 * [2] = number of matches participated in
	 * [3] = number of correctly solved puzzles
	 */
	public void getUserProperties(String handle, AsyncCallback callback);
	
	/**
	 * This will update the result of a matching game after a player has finished
	 * playing the game
	 * @param gameHandle The name of the game that has ended
	 * @param finished Whether the player successfully completed the matching game
	 * @param score The player's score in finishing the game
	 * @return whether the server has successfully processed the update
	 */
	public void matchingResult(String gameHandle, boolean finished, double score, AsyncCallback callback);
	
	/**
	 * This will allow a player to be able to participate in a head to head game
	 * @param playerNum The temporary number of the player to participate
	 * @return The ID of the head to head game
	 */
	public void startNewHead2HeadGame(int playerNum, AsyncCallback callback);
	
	/**
	 * This will return the matching associated with the given head to head
	 * game number.
	 * @param gameNum The number of the game to find the matching for
	 * @return The game's matching
	 */
	public void getHead2HeadMatching(int gameNum, AsyncCallback callback);
	
	/**
	 * This will allow players to check if a head to head game has already been
	 * won.  If it hasn't then the given player will be declared the winner.
	 * @param gameNum The game number to be checked
	 * @return True if the game has already been won
	 */
	public void checkHead2HeadGameWon(int gameNum, AsyncCallback callback);
}